home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / docs / gas / as.i2 < prev    next >
Encoding:
GNU Info File  |  1994-12-17  |  49.3 KB  |  1,472 lines
  1. This is Info file as.info, produced by Makeinfo-1.55 from the input
  2. file ./as.texinfo.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * As: (as).                     The GNU assembler.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This file documents the GNU Assembler "as".
  9.  
  10.    Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
  11.  
  12.    Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.    Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that
  18. the entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21.    Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions.
  24.  
  25. 
  26. File: as.info,  Node: Labels,  Next: Setting Symbols,  Up: Symbols
  27.  
  28. Labels
  29. ======
  30.  
  31.    A "label" is written as a symbol immediately followed by a colon
  32. `:'.  The symbol then represents the current value of the active
  33. location counter, and is, for example, a suitable instruction operand.
  34. You are warned if you use the same symbol to represent two different
  35. locations: the first definition overrides any other definitions.
  36.  
  37.    On the HPPA, the usual form for a label need not be immediately
  38. followed by a colon, but instead must start in column zero.  Only one
  39. label may be defined on a single line.  To work around this, the HPPA
  40. version of `as' also provides a special directive `.label' for defining
  41. labels more flexibly.
  42.  
  43. 
  44. File: as.info,  Node: Setting Symbols,  Next: Symbol Names,  Prev: Labels,  Up: Symbols
  45.  
  46. Giving Symbols Other Values
  47. ===========================
  48.  
  49.    A symbol can be given an arbitrary value by writing a symbol,
  50. followed by an equals sign `=', followed by an expression (*note
  51. Expressions::.).  This is equivalent to using the `.set' directive.
  52. *Note `.set': Set.
  53.  
  54. 
  55. File: as.info,  Node: Symbol Names,  Next: Dot,  Prev: Setting Symbols,  Up: Symbols
  56.  
  57. Symbol Names
  58. ============
  59.  
  60.    Symbol names begin with a letter or with one of `._'.  On most
  61. machines, you can also use `$' in symbol names; exceptions are noted in
  62. *Note Machine Dependencies::.  That character may be followed by any
  63. string of digits, letters, dollar signs (unless otherwise noted in
  64. *Note Machine Dependencies::), and underscores.  For the AMD 29K
  65. family, `?' is also allowed in the body of a symbol name, though not at
  66. its beginning.
  67.  
  68.    Case of letters is significant: `foo' is a different symbol name
  69. than `Foo'.
  70.  
  71.    Each symbol has exactly one name.  Each name in an assembly language
  72. program refers to exactly one symbol.  You may use that symbol name any
  73. number of times in a program.
  74.  
  75. Local Symbol Names
  76. ------------------
  77.  
  78.    Local symbols help compilers and programmers use names temporarily.
  79. There are ten local symbol names, which are re-used throughout the
  80. program.  You may refer to them using the names `0' `1' ... `9'.  To
  81. define a local symbol, write a label of the form `N:' (where N
  82. represents any digit).  To refer to the most recent previous definition
  83. of that symbol write `Nb', using the same digit as when you defined the
  84. label.  To refer to the next definition of a local label, write
  85. `Nf'--where N gives you a choice of 10 forward references.  The `b'
  86. stands for "backwards" and the `f' stands for "forwards".
  87.  
  88.    Local symbols are not emitted by the current GNU C compiler.
  89.  
  90.    There is no restriction on how you can use these labels, but
  91. remember that at any point in the assembly you can refer to at most 10
  92. prior local labels and to at most 10 forward local labels.
  93.  
  94.    Local symbol names are only a notation device.  They are immediately
  95. transformed into more conventional symbol names before the assembler
  96. uses them.  The symbol names stored in the symbol table, appearing in
  97. error messages and optionally emitted to the object file have these
  98. parts:
  99.  
  100. `L'
  101.      All local labels begin with `L'. Normally both `as' and `ld'
  102.      forget symbols that start with `L'. These labels are used for
  103.      symbols you are never intended to see.  If you use the `-L' option
  104.      then `as' retains these symbols in the object file. If you also
  105.      instruct `ld' to retain these symbols, you may use them in
  106.      debugging.
  107.  
  108. `DIGIT'
  109.      If the label is written `0:' then the digit is `0'.  If the label
  110.      is written `1:' then the digit is `1'.  And so on up through `9:'.
  111.  
  112. A'
  113.      This unusual character is included so you do not accidentally
  114.      invent a symbol of the same name.  The character has ASCII value
  115.      `\001'.
  116.  
  117. `*ordinal number*'
  118.      This is a serial number to keep the labels distinct.  The first
  119.      `0:' gets the number `1'; The 15th `0:' gets the number `15';
  120.      *etc.*.  Likewise for the other labels `1:' through `9:'.
  121.  
  122.    For instance, the first `1:' is named `LA1', the 44th `3:' is named
  123. `LA44'.
  124.  
  125. 
  126. File: as.info,  Node: Dot,  Next: Symbol Attributes,  Prev: Symbol Names,  Up: Symbols
  127.  
  128. The Special Dot Symbol
  129. ======================
  130.  
  131.    The special symbol `.' refers to the current address that `as' is
  132. assembling into.  Thus, the expression `melvin: .long .' defines
  133. `melvin' to contain its own address.  Assigning a value to `.' is
  134. treated the same as a `.org' directive.  Thus, the expression `.=.+4'
  135. is the same as saying `.space 4'.
  136.  
  137. 
  138. File: as.info,  Node: Symbol Attributes,  Prev: Dot,  Up: Symbols
  139.  
  140. Symbol Attributes
  141. =================
  142.  
  143.    Every symbol has, as well as its name, the attributes "Value" and
  144. "Type".  Depending on output format, symbols can also have auxiliary
  145. attributes.
  146.  
  147.    If you use a symbol without defining it, `as' assumes zero for all
  148. these attributes, and probably won't warn you.  This makes the symbol
  149. an externally defined symbol, which is generally what you would want.
  150.  
  151. * Menu:
  152.  
  153. * Symbol Value::                Value
  154. * Symbol Type::                 Type
  155.  
  156.  
  157. * a.out Symbols::               Symbol Attributes: `a.out'
  158.  
  159. * COFF Symbols::                Symbol Attributes for COFF
  160.  
  161. * SOM Symbols::                Symbol Attributes for SOM
  162.  
  163. 
  164. File: as.info,  Node: Symbol Value,  Next: Symbol Type,  Up: Symbol Attributes
  165.  
  166. Value
  167. -----
  168.  
  169.    The value of a symbol is (usually) 32 bits.  For a symbol which
  170. labels a location in the text, data, bss or absolute sections the value
  171. is the number of addresses from the start of that section to the label.
  172. Naturally for text, data and bss sections the value of a symbol changes
  173. as `ld' changes section base addresses during linking.  Absolute
  174. symbols' values do not change during linking: that is why they are
  175. called absolute.
  176.  
  177.    The value of an undefined symbol is treated in a special way.  If it
  178. is 0 then the symbol is not defined in this assembler source file, and
  179. `ld' tries to determine its value from other files linked into the same
  180. program.  You make this kind of symbol simply by mentioning a symbol
  181. name without defining it.  A non-zero value represents a `.comm' common
  182. declaration.  The value is how much common storage to reserve, in bytes
  183. (addresses).  The symbol refers to the first address of the allocated
  184. storage.
  185.  
  186. 
  187. File: as.info,  Node: Symbol Type,  Next: a.out Symbols,  Prev: Symbol Value,  Up: Symbol Attributes
  188.  
  189. Type
  190. ----
  191.  
  192.    The type attribute of a symbol contains relocation (section)
  193. information, any flag settings indicating that a symbol is external, and
  194. (optionally), other information for linkers and debuggers.  The exact
  195. format depends on the object-code output format in use.
  196.  
  197. 
  198. File: as.info,  Node: a.out Symbols,  Next: COFF Symbols,  Prev: Symbol Type,  Up: Symbol Attributes
  199.  
  200. Symbol Attributes: `a.out'
  201. --------------------------
  202.  
  203. * Menu:
  204.  
  205. * Symbol Desc::                 Descriptor
  206. * Symbol Other::                Other
  207.  
  208. 
  209. File: as.info,  Node: Symbol Desc,  Next: Symbol Other,  Up: a.out Symbols
  210.  
  211. Descriptor
  212. ..........
  213.  
  214.    This is an arbitrary 16-bit value.  You may establish a symbol's
  215. descriptor value by using a `.desc' statement (*note `.desc': Desc.).
  216. A descriptor value means nothing to `as'.
  217.  
  218. 
  219. File: as.info,  Node: Symbol Other,  Prev: Symbol Desc,  Up: a.out Symbols
  220.  
  221. Other
  222. .....
  223.  
  224.    This is an arbitrary 8-bit value.  It means nothing to `as'.
  225.  
  226. 
  227. File: as.info,  Node: COFF Symbols,  Next: SOM Symbols,  Prev: a.out Symbols,  Up: Symbol Attributes
  228.  
  229. Symbol Attributes for COFF
  230. --------------------------
  231.  
  232.    The COFF format supports a multitude of auxiliary symbol attributes;
  233. like the primary symbol attributes, they are set between `.def' and
  234. `.endef' directives.
  235.  
  236. Primary Attributes
  237. ..................
  238.  
  239.    The symbol name is set with `.def'; the value and type,
  240. respectively, with `.val' and `.type'.
  241.  
  242. Auxiliary Attributes
  243. ....................
  244.  
  245.    The `as' directives `.dim', `.line', `.scl', `.size', and `.tag' can
  246. generate auxiliary symbol table information for COFF.
  247.  
  248. 
  249. File: as.info,  Node: SOM Symbols,  Prev: COFF Symbols,  Up: Symbol Attributes
  250.  
  251. Symbol Attributes for SOM
  252. -------------------------
  253.  
  254.    The SOM format for the HPPA supports a multitude of symbol
  255. attributes set with the `.EXPORT' and `.IMPORT' directives.
  256.  
  257.    The attributes are described in `HP9000 Series 800 Assembly Language
  258. Reference Manual' (HP 92432-90001) under the `IMPORT' and `EXPORT'
  259. assembler directive documentation.
  260.  
  261. 
  262. File: as.info,  Node: Expressions,  Next: Pseudo Ops,  Prev: Symbols,  Up: Top
  263.  
  264. Expressions
  265. ***********
  266.  
  267.    An "expression" specifies an address or numeric value.  Whitespace
  268. may precede and/or follow an expression.
  269.  
  270.    The result of an expression must be an absolute number, or else an
  271. offset into a particular section.  If an expression is not absolute,
  272. and there is not enough information when `as' sees the expression to
  273. know its section, a second pass over the source program might be
  274. necessary to interpret the expression--but the second pass is currently
  275. not implemented.  `as' aborts with an error message in this situation.
  276.  
  277. * Menu:
  278.  
  279. * Empty Exprs::                 Empty Expressions
  280. * Integer Exprs::               Integer Expressions
  281.  
  282. 
  283. File: as.info,  Node: Empty Exprs,  Next: Integer Exprs,  Up: Expressions
  284.  
  285. Empty Expressions
  286. =================
  287.  
  288.    An empty expression has no value: it is just whitespace or null.
  289. Wherever an absolute expression is required, you may omit the
  290. expression, and `as' assumes a value of (absolute) 0.  This is
  291. compatible with other assemblers.
  292.  
  293. 
  294. File: as.info,  Node: Integer Exprs,  Prev: Empty Exprs,  Up: Expressions
  295.  
  296. Integer Expressions
  297. ===================
  298.  
  299.    An "integer expression" is one or more *arguments* delimited by
  300. *operators*.
  301.  
  302. * Menu:
  303.  
  304. * Arguments::                   Arguments
  305. * Operators::                   Operators
  306. * Prefix Ops::                  Prefix Operators
  307. * Infix Ops::                   Infix Operators
  308.  
  309. 
  310. File: as.info,  Node: Arguments,  Next: Operators,  Up: Integer Exprs
  311.  
  312. Arguments
  313. ---------
  314.  
  315.    "Arguments" are symbols, numbers or subexpressions.  In other
  316. contexts arguments are sometimes called "arithmetic operands".  In this
  317. manual, to avoid confusing them with the "instruction operands" of the
  318. machine language, we use the term "argument" to refer to parts of
  319. expressions only, reserving the word "operand" to refer only to machine
  320. instruction operands.
  321.  
  322.    Symbols are evaluated to yield {SECTION NNN} where SECTION is one of
  323. text, data, bss, absolute, or undefined.  NNN is a signed, 2's
  324. complement 32 bit integer.
  325.  
  326.    Numbers are usually integers.
  327.  
  328.    A number can be a flonum or bignum.  In this case, you are warned
  329. that only the low order 32 bits are used, and `as' pretends these 32
  330. bits are an integer.  You may write integer-manipulating instructions
  331. that act on exotic constants, compatible with other assemblers.
  332.  
  333.    Subexpressions are a left parenthesis `(' followed by an integer
  334. expression, followed by a right parenthesis `)'; or a prefix operator
  335. followed by an argument.
  336.  
  337. 
  338. File: as.info,  Node: Operators,  Next: Prefix Ops,  Prev: Arguments,  Up: Integer Exprs
  339.  
  340. Operators
  341. ---------
  342.  
  343.    "Operators" are arithmetic functions, like `+' or `%'.  Prefix
  344. operators are followed by an argument.  Infix operators appear between
  345. their arguments.  Operators may be preceded and/or followed by
  346. whitespace.
  347.  
  348. 
  349. File: as.info,  Node: Prefix Ops,  Next: Infix Ops,  Prev: Operators,  Up: Integer Exprs
  350.  
  351. Prefix Operator
  352. ---------------
  353.  
  354.    `as' has the following "prefix operators".  They each take one
  355. argument, which must be absolute.
  356.  
  357. `-'
  358.      "Negation".  Two's complement negation.
  359.  
  360. `~'
  361.      "Complementation".  Bitwise not.
  362.  
  363. 
  364. File: as.info,  Node: Infix Ops,  Prev: Prefix Ops,  Up: Integer Exprs
  365.  
  366. Infix Operators
  367. ---------------
  368.  
  369.    "Infix operators" take two arguments, one on either side.  Operators
  370. have precedence, but operations with equal precedence are performed left
  371. to right.  Apart from `+' or `-', both arguments must be absolute, and
  372. the result is absolute.
  373.  
  374.   1. Highest Precedence
  375.  
  376.     `*'
  377.           "Multiplication".
  378.  
  379.     `/'
  380.           "Division".  Truncation is the same as the C operator `/'
  381.  
  382.     `%'
  383.           "Remainder".
  384.  
  385.     `<'
  386.     `<<'
  387.           "Shift Left".  Same as the C operator `<<'.
  388.  
  389.     `>'
  390.     `>>'
  391.           "Shift Right".  Same as the C operator `>>'.
  392.  
  393.   2. Intermediate precedence
  394.  
  395.     `|'
  396.           "Bitwise Inclusive Or".
  397.  
  398.     `&'
  399.           "Bitwise And".
  400.  
  401.     `^'
  402.           "Bitwise Exclusive Or".
  403.  
  404.     `!'
  405.           "Bitwise Or Not".
  406.  
  407.   3. Lowest Precedence
  408.  
  409.     `+'
  410.           "Addition".  If either argument is absolute, the result has
  411.           the section of the other argument.  You may not add together
  412.           arguments from different sections.
  413.  
  414.     `-'
  415.           "Subtraction".  If the right argument is absolute, the result
  416.           has the section of the left argument.  If both arguments are
  417.           in the same section, the result is absolute.  You may not
  418.           subtract arguments from different sections.
  419.  
  420.    In short, it's only meaningful to add or subtract the *offsets* in an
  421. address; you can only have a defined section in one of the two
  422. arguments.
  423.  
  424. 
  425. File: as.info,  Node: Pseudo Ops,  Next: Machine Dependencies,  Prev: Expressions,  Up: Top
  426.  
  427. Assembler Directives
  428. ********************
  429.  
  430.    All assembler directives have names that begin with a period (`.').
  431. The rest of the name is letters, usually in lower case.
  432.  
  433.    This chapter discusses directives that are available regardless of
  434. the target machine configuration for the GNU assembler.  Some machine
  435. configurations provide additional directives.  *Note Machine
  436. Dependencies::.
  437.  
  438. * Menu:
  439.  
  440. * Abort::                       `.abort'
  441.  
  442. * ABORT::                       `.ABORT'
  443.  
  444. * Align::                       `.align ABS-EXPR , ABS-EXPR'
  445. * App-File::                    `.app-file STRING'
  446. * Ascii::                       `.ascii "STRING"'...
  447. * Asciz::                       `.asciz "STRING"'...
  448. * Byte::                        `.byte EXPRESSIONS'
  449. * Comm::                        `.comm SYMBOL , LENGTH '
  450. * Data::                        `.data SUBSECTION'
  451.  
  452. * Def::                         `.def NAME'
  453.  
  454. * Desc::                        `.desc SYMBOL, ABS-EXPRESSION'
  455.  
  456. * Dim::                         `.dim'
  457.  
  458. * Double::                      `.double FLONUMS'
  459. * Eject::                       `.eject'
  460. * Else::                        `.else'
  461.  
  462. * Endef::                       `.endef'
  463.  
  464. * Endif::                       `.endif'
  465. * Equ::                         `.equ SYMBOL, EXPRESSION'
  466. * Extern::                      `.extern'
  467.  
  468. * File::                        `.file STRING'
  469.  
  470. * Fill::                        `.fill REPEAT , SIZE , VALUE'
  471. * Float::                       `.float FLONUMS'
  472. * Global::                      `.global SYMBOL', `.globl SYMBOL'
  473. * hword::                       `.hword EXPRESSIONS'
  474. * Ident::                       `.ident'
  475. * If::                          `.if ABSOLUTE EXPRESSION'
  476. * Include::                     `.include "FILE"'
  477. * Int::                         `.int EXPRESSIONS'
  478. * Lcomm::                       `.lcomm SYMBOL , LENGTH'
  479. * Lflags::                      `.lflags'
  480.  
  481. * Line::                        `.line LINE-NUMBER'
  482.  
  483. * Ln::                          `.ln LINE-NUMBER'
  484. * List::                        `.list'
  485. * Long::                        `.long EXPRESSIONS'
  486.  
  487. * Nolist::                      `.nolist'
  488. * Octa::                        `.octa BIGNUMS'
  489. * Org::                         `.org NEW-LC , FILL'
  490. * Psize::                       `.psize LINES, COLUMNS'
  491. * Quad::                        `.quad BIGNUMS'
  492. * Sbttl::                       `.sbttl "SUBHEADING"'
  493.  
  494. * Scl::                         `.scl CLASS'
  495.  
  496. * Section::                     `.section NAME, SUBSECTION'
  497.  
  498. * Set::                         `.set SYMBOL, EXPRESSION'
  499. * Short::                       `.short EXPRESSIONS'
  500. * Single::                      `.single FLONUMS'
  501.  
  502. * Size::                        `.size'
  503.  
  504. * Space::                       `.space SIZE , FILL'
  505.  
  506. * Stab::                        `.stabd, .stabn, .stabs'
  507.  
  508. * String::                      `.string "STR"'
  509.  
  510. * Tag::                         `.tag STRUCTNAME'
  511.  
  512. * Text::                        `.text SUBSECTION'
  513. * Title::                       `.title "HEADING"'
  514.  
  515. * Type::                        `.type INT'
  516. * Val::                         `.val ADDR'
  517.  
  518. * Word::                        `.word EXPRESSIONS'
  519. * Deprecated::                  Deprecated Directives
  520.  
  521. 
  522. File: as.info,  Node: Abort,  Next: ABORT,  Up: Pseudo Ops
  523.  
  524. `.abort'
  525. ========
  526.  
  527.    This directive stops the assembly immediately.  It is for
  528. compatibility with other assemblers.  The original idea was that the
  529. assembly language source would be piped into the assembler.  If the
  530. sender of the source quit, it could use this directive tells `as' to
  531. quit also.  One day `.abort' will not be supported.
  532.  
  533. 
  534. File: as.info,  Node: ABORT,  Next: Align,  Prev: Abort,  Up: Pseudo Ops
  535.  
  536. `.ABORT'
  537. ========
  538.  
  539.    When producing COFF output, `as' accepts this directive as a synonym
  540. for `.abort'.
  541.  
  542.    When producing `b.out' output, `as' accepts this directive, but
  543. ignores it.
  544.  
  545. 
  546. File: as.info,  Node: Align,  Next: App-File,  Prev: ABORT,  Up: Pseudo Ops
  547.  
  548. `.align ABS-EXPR , ABS-EXPR'
  549. ============================
  550.  
  551.    Pad the location counter (in the current subsection) to a particular
  552. storage boundary.  The first expression (which must be absolute) is the
  553. number of low-order zero bits the location counter must have after
  554. advancement.  For example `.align 3' advances the location counter
  555. until it a multiple of 8.  If the location counter is already a
  556. multiple of 8, no change is needed.
  557.  
  558.    For the HPPA, the first expression (which must be absolute) is the
  559. alignment request in bytes.  For example `.align 8' advances the
  560. location counter until it is a multiple of 8.  If the location counter
  561. is already a multiple of 8, no change is needed.
  562.  
  563.    The second expression (also absolute) gives the value to be stored in
  564. the padding bytes.  It (and the comma) may be omitted.  If it is
  565. omitted, the padding bytes are zero.
  566.  
  567. 
  568. File: as.info,  Node: App-File,  Next: Ascii,  Prev: Align,  Up: Pseudo Ops
  569.  
  570. `.app-file STRING'
  571. ==================
  572.  
  573.    `.app-file' (which may also be spelled `.file') tells `as' that we
  574. are about to start a new logical file.  STRING is the new file name.
  575. In general, the filename is recognized whether or not it is surrounded
  576. by quotes `"'; but if you wish to specify an empty file name is
  577. permitted, you must give the quotes-`""'.  This statement may go away in
  578. future: it is only recognized to be compatible with old `as' programs.
  579.  
  580. 
  581. File: as.info,  Node: Ascii,  Next: Asciz,  Prev: App-File,  Up: Pseudo Ops
  582.  
  583. `.ascii "STRING"'...
  584. ====================
  585.  
  586.    `.ascii' expects zero or more string literals (*note Strings::.)
  587. separated by commas.  It assembles each string (with no automatic
  588. trailing zero byte) into consecutive addresses.
  589.  
  590. 
  591. File: as.info,  Node: Asciz,  Next: Byte,  Prev: Ascii,  Up: Pseudo Ops
  592.  
  593. `.asciz "STRING"'...
  594. ====================
  595.  
  596.    `.asciz' is just like `.ascii', but each string is followed by a
  597. zero byte.  The "z" in `.asciz' stands for "zero".
  598.  
  599. 
  600. File: as.info,  Node: Byte,  Next: Comm,  Prev: Asciz,  Up: Pseudo Ops
  601.  
  602. `.byte EXPRESSIONS'
  603. ===================
  604.  
  605.    `.byte' expects zero or more expressions, separated by commas.  Each
  606. expression is assembled into the next byte.
  607.  
  608. 
  609. File: as.info,  Node: Comm,  Next: Data,  Prev: Byte,  Up: Pseudo Ops
  610.  
  611. `.comm SYMBOL , LENGTH '
  612. ========================
  613.  
  614.    `.comm' declares a named common area in the bss section.  Normally
  615. `ld' reserves memory addresses for it during linking, so no partial
  616. program defines the location of the symbol.  Use `.comm' to tell `ld'
  617. that it must be at least LENGTH bytes long.  `ld' allocates space for
  618. each `.comm' symbol that is at least as long as the longest `.comm'
  619. request in any of the partial programs linked.  LENGTH is an absolute
  620. expression.
  621.  
  622.    The syntax for `.comm' differs slightly on the HPPA.  The syntax is
  623. `SYMBOL .comm, LENGTH'; SYMBOL is optional.
  624.  
  625. 
  626. File: as.info,  Node: Data,  Next: Def,  Prev: Comm,  Up: Pseudo Ops
  627.  
  628. `.data SUBSECTION'
  629. ==================
  630.  
  631.    `.data' tells `as' to assemble the following statements onto the end
  632. of the data subsection numbered SUBSECTION (which is an absolute
  633. expression).  If SUBSECTION is omitted, it defaults to zero.
  634.  
  635. 
  636. File: as.info,  Node: Def,  Next: Desc,  Prev: Data,  Up: Pseudo Ops
  637.  
  638. `.def NAME'
  639. ===========
  640.  
  641.    Begin defining debugging information for a symbol NAME; the
  642. definition extends until the `.endef' directive is encountered.
  643.  
  644.    This directive is only observed when `as' is configured for COFF
  645. format output; when producing `b.out', `.def' is recognized, but
  646. ignored.
  647.  
  648. 
  649. File: as.info,  Node: Desc,  Next: Dim,  Prev: Def,  Up: Pseudo Ops
  650.  
  651. `.desc SYMBOL, ABS-EXPRESSION'
  652. ==============================
  653.  
  654.    This directive sets the descriptor of the symbol (*note Symbol
  655. Attributes::.) to the low 16 bits of an absolute expression.
  656.  
  657.    The `.desc' directive is not available when `as' is configured for
  658. COFF output; it is only for `a.out' or `b.out' object format.  For the
  659. sake of compatibility, `as' accepts it, but produces no output, when
  660. configured for COFF.
  661.  
  662. 
  663. File: as.info,  Node: Dim,  Next: Double,  Prev: Desc,  Up: Pseudo Ops
  664.  
  665. `.dim'
  666. ======
  667.  
  668.    This directive is generated by compilers to include auxiliary
  669. debugging information in the symbol table.  It is only permitted inside
  670. `.def'/`.endef' pairs.
  671.  
  672.    `.dim' is only meaningful when generating COFF format output; when
  673. `as' is generating `b.out', it accepts this directive but ignores it.
  674.  
  675. 
  676. File: as.info,  Node: Double,  Next: Eject,  Prev: Dim,  Up: Pseudo Ops
  677.  
  678. `.double FLONUMS'
  679. =================
  680.  
  681.    `.double' expects zero or more flonums, separated by commas.  It
  682. assembles floating point numbers.  The exact kind of floating point
  683. numbers emitted depends on how `as' is configured.  *Note Machine
  684. Dependencies::.
  685.  
  686. 
  687. File: as.info,  Node: Eject,  Next: Else,  Prev: Double,  Up: Pseudo Ops
  688.  
  689. `.eject'
  690. ========
  691.  
  692.    Force a page break at this point, when generating assembly listings.
  693.  
  694. 
  695. File: as.info,  Node: Else,  Next: Endef,  Prev: Eject,  Up: Pseudo Ops
  696.  
  697. `.else'
  698. =======
  699.  
  700.    `.else' is part of the `as' support for conditional assembly; *note
  701. `.if': If..  It marks the beginning of a section of code to be
  702. assembled if the condition for the preceding `.if' was false.
  703.  
  704. 
  705. File: as.info,  Node: Endef,  Next: Endif,  Prev: Else,  Up: Pseudo Ops
  706.  
  707. `.endef'
  708. ========
  709.  
  710.    This directive flags the end of a symbol definition begun with
  711. `.def'.
  712.  
  713.    `.endef' is only meaningful when generating COFF format output; if
  714. `as' is configured to generate `b.out', it accepts this directive but
  715. ignores it.
  716.  
  717. 
  718. File: as.info,  Node: Endif,  Next: Equ,  Prev: Endef,  Up: Pseudo Ops
  719.  
  720. `.endif'
  721. ========
  722.  
  723.    `.endif' is part of the `as' support for conditional assembly; it
  724. marks the end of a block of code that is only assembled conditionally.
  725. *Note `.if': If.
  726.  
  727. 
  728. File: as.info,  Node: Equ,  Next: Extern,  Prev: Endif,  Up: Pseudo Ops
  729.  
  730. `.equ SYMBOL, EXPRESSION'
  731. =========================
  732.  
  733.    This directive sets the value of SYMBOL to EXPRESSION.  It is
  734. synonymous with `.set'; *note `.set': Set..
  735.  
  736.    The syntax for `equ' on the HPPA is `SYMBOL .equ EXPRESSION'.
  737.  
  738. 
  739. File: as.info,  Node: Extern,  Next: File,  Prev: Equ,  Up: Pseudo Ops
  740.  
  741. `.extern'
  742. =========
  743.  
  744.    `.extern' is accepted in the source program--for compatibility with
  745. other assemblers--but it is ignored.  `as' treats all undefined symbols
  746. as external.
  747.  
  748. 
  749. File: as.info,  Node: File,  Next: Fill,  Prev: Extern,  Up: Pseudo Ops
  750.  
  751. `.file STRING'
  752. ==============
  753.  
  754.    `.file' (which may also be spelled `.app-file') tells `as' that we
  755. are about to start a new logical file.  STRING is the new file name.
  756. In general, the filename is recognized whether or not it is surrounded
  757. by quotes `"'; but if you wish to specify an empty file name, you must
  758. give the quotes-`""'.  This statement may go away in future: it is only
  759. recognized to be compatible with old `as' programs.  In some
  760. configurations of `as', `.file' has already been removed to avoid
  761. conflicts with other assemblers.  *Note Machine Dependencies::.
  762.  
  763. 
  764. File: as.info,  Node: Fill,  Next: Float,  Prev: File,  Up: Pseudo Ops
  765.  
  766. `.fill REPEAT , SIZE , VALUE'
  767. =============================
  768.  
  769.    RESULT, SIZE and VALUE are absolute expressions.  This emits REPEAT
  770. copies of SIZE bytes.  REPEAT may be zero or more.  SIZE may be zero or
  771. more, but if it is more than 8, then it is deemed to have the value 8,
  772. compatible with other people's assemblers.  The contents of each REPEAT
  773. bytes is taken from an 8-byte number.  The highest order 4 bytes are
  774. zero.  The lowest order 4 bytes are VALUE rendered in the byte-order of
  775. an integer on the computer `as' is assembling for.  Each SIZE bytes in
  776. a repetition is taken from the lowest order SIZE bytes of this number.
  777. Again, this bizarre behavior is compatible with other people's
  778. assemblers.
  779.  
  780.    SIZE and VALUE are optional.  If the second comma and VALUE are
  781. absent, VALUE is assumed zero.  If the first comma and following tokens
  782. are absent, SIZE is assumed to be 1.
  783.  
  784. 
  785. File: as.info,  Node: Float,  Next: Global,  Prev: Fill,  Up: Pseudo Ops
  786.  
  787. `.float FLONUMS'
  788. ================
  789.  
  790.    This directive assembles zero or more flonums, separated by commas.
  791. It has the same effect as `.single'.  The exact kind of floating point
  792. numbers emitted depends on how `as' is configured.  *Note Machine
  793. Dependencies::.
  794.  
  795. 
  796. File: as.info,  Node: Global,  Next: hword,  Prev: Float,  Up: Pseudo Ops
  797.  
  798. `.global SYMBOL', `.globl SYMBOL'
  799. =================================
  800.  
  801.    `.global' makes the symbol visible to `ld'.  If you define SYMBOL in
  802. your partial program, its value is made available to other partial
  803. programs that are linked with it.  Otherwise, SYMBOL takes its
  804. attributes from a symbol of the same name from another file linked into
  805. the same program.
  806.  
  807.    Both spellings (`.globl' and `.global') are accepted, for
  808. compatibility with other assemblers.
  809.  
  810.    On the HPPA, `.global' is not always enough to make it accessible to
  811. other partial programs.  You may need the HPPA-only `.EXPORT' directive
  812. as well.  *Note HPPA Assembler Directives: HPPA Directives.
  813.  
  814. 
  815. File: as.info,  Node: hword,  Next: Ident,  Prev: Global,  Up: Pseudo Ops
  816.  
  817. `.hword EXPRESSIONS'
  818. ====================
  819.  
  820.    This expects zero or more EXPRESSIONS, and emits a 16 bit number for
  821. each.
  822.  
  823.    This directive is a synonym for `.short'; depending on the target
  824. architecture, it may also be a synonym for `.word'.
  825.  
  826. 
  827. File: as.info,  Node: Ident,  Next: If,  Prev: hword,  Up: Pseudo Ops
  828.  
  829. `.ident'
  830. ========
  831.  
  832.    This directive is used by some assemblers to place tags in object
  833. files.  `as' simply accepts the directive for source-file compatibility
  834. with such assemblers, but does not actually emit anything for it.
  835.  
  836. 
  837. File: as.info,  Node: If,  Next: Include,  Prev: Ident,  Up: Pseudo Ops
  838.  
  839. `.if ABSOLUTE EXPRESSION'
  840. =========================
  841.  
  842.    `.if' marks the beginning of a section of code which is only
  843. considered part of the source program being assembled if the argument
  844. (which must be an ABSOLUTE EXPRESSION) is non-zero.  The end of the
  845. conditional section of code must be marked by `.endif' (*note `.endif':
  846. Endif.); optionally, you may include code for the alternative
  847. condition, flagged by `.else' (*note `.else': Else..
  848.  
  849.    The following variants of `.if' are also supported:
  850. `.ifdef SYMBOL'
  851.      Assembles the following section of code if the specified SYMBOL
  852.      has been defined.
  853.  
  854. `.ifndef SYMBOL'
  855. `ifnotdef SYMBOL'
  856.      Assembles the following section of code if the specified SYMBOL
  857.      has not been defined.  Both spelling variants are equivalent.
  858.  
  859. 
  860. File: as.info,  Node: Include,  Next: Int,  Prev: If,  Up: Pseudo Ops
  861.  
  862. `.include "FILE"'
  863. =================
  864.  
  865.    This directive provides a way to include supporting files at
  866. specified points in your source program.  The code from FILE is
  867. assembled as if it followed the point of the `.include'; when the end
  868. of the included file is reached, assembly of the original file
  869. continues.  You can control the search paths used with the `-I'
  870. command-line option (*note Command-Line Options: Invoking.).  Quotation
  871. marks are required around FILE.
  872.  
  873. 
  874. File: as.info,  Node: Int,  Next: Lcomm,  Prev: Include,  Up: Pseudo Ops
  875.  
  876. `.int EXPRESSIONS'
  877. ==================
  878.  
  879.    Expect zero or more EXPRESSIONS, of any section, separated by commas.
  880. For each expression, emit a number that, at run time, is the value of
  881. that expression.  The byte order and bit size of the number depends on
  882. what kind of target the assembly is for.
  883.  
  884. 
  885. File: as.info,  Node: Lcomm,  Next: Lflags,  Prev: Int,  Up: Pseudo Ops
  886.  
  887. `.lcomm SYMBOL , LENGTH'
  888. ========================
  889.  
  890.    Reserve LENGTH (an absolute expression) bytes for a local common
  891. denoted by SYMBOL.  The section and value of SYMBOL are those of the
  892. new local common.  The addresses are allocated in the bss section, so
  893. that at run-time the bytes start off zeroed.  SYMBOL is not declared
  894. global (*note `.global': Global.), so is normally not visible to `ld'.
  895.  
  896.    The syntax for `.lcomm' differs slightly on the HPPA.  The syntax is
  897. `SYMBOL .lcomm, LENGTH'; SYMBOL is optional.
  898.  
  899. 
  900. File: as.info,  Node: Lflags,  Next: Line,  Prev: Lcomm,  Up: Pseudo Ops
  901.  
  902. `.lflags'
  903. =========
  904.  
  905.    `as' accepts this directive, for compatibility with other
  906. assemblers, but ignores it.
  907.  
  908. 
  909. File: as.info,  Node: Line,  Next: Ln,  Prev: Lflags,  Up: Pseudo Ops
  910.  
  911. `.line LINE-NUMBER'
  912. ===================
  913.  
  914.    Change the logical line number.  LINE-NUMBER must be an absolute
  915. expression.  The next line has that logical line number.  Therefore any
  916. other statements on the current line (after a statement separator
  917. character) are reported as on logical line number LINE-NUMBER - 1.  One
  918. day `as' will no longer support this directive: it is recognized only
  919. for compatibility with existing assembler programs.
  920.  
  921.    *Warning:* In the AMD29K configuration of as, this command is not
  922. available; use the synonym `.ln' in that context.
  923.  
  924.    Even though this is a directive associated with the `a.out' or
  925. `b.out' object-code formats, `as' still recognizes it when producing
  926. COFF output, and treats `.line' as though it were the COFF `.ln' *if*
  927. it is found outside a `.def'/`.endef' pair.
  928.  
  929.    Inside a `.def', `.line' is, instead, one of the directives used by
  930. compilers to generate auxiliary symbol information for debugging.
  931.  
  932. 
  933. File: as.info,  Node: Ln,  Next: List,  Prev: Line,  Up: Pseudo Ops
  934.  
  935. `.ln LINE-NUMBER'
  936. =================
  937.  
  938.    `.ln' is a synonym for `.line'.
  939.  
  940. 
  941. File: as.info,  Node: List,  Next: Long,  Prev: Ln,  Up: Pseudo Ops
  942.  
  943. `.list'
  944. =======
  945.  
  946.    Control (in conjunction with the `.nolist' directive) whether or not
  947. assembly listings are generated.  These two directives maintain an
  948. internal counter (which is zero initially).   `.list' increments the
  949. counter, and `.nolist' decrements it.  Assembly listings are generated
  950. whenever the counter is greater than zero.
  951.  
  952.    By default, listings are disabled.  When you enable them (with the
  953. `-a' command line option; *note Command-Line Options: Invoking.), the
  954. initial value of the listing counter is one.
  955.  
  956. 
  957. File: as.info,  Node: Long,  Next: Nolist,  Prev: List,  Up: Pseudo Ops
  958.  
  959. `.long EXPRESSIONS'
  960. ===================
  961.  
  962.    `.long' is the same as `.int', *note `.int': Int..
  963.  
  964. 
  965. File: as.info,  Node: Nolist,  Next: Octa,  Prev: Long,  Up: Pseudo Ops
  966.  
  967. `.nolist'
  968. =========
  969.  
  970.    Control (in conjunction with the `.list' directive) whether or not
  971. assembly listings are generated.  These two directives maintain an
  972. internal counter (which is zero initially).   `.list' increments the
  973. counter, and `.nolist' decrements it.  Assembly listings are generated
  974. whenever the counter is greater than zero.
  975.  
  976. 
  977. File: as.info,  Node: Octa,  Next: Org,  Prev: Nolist,  Up: Pseudo Ops
  978.  
  979. `.octa BIGNUMS'
  980. ===============
  981.  
  982.    This directive expects zero or more bignums, separated by commas.
  983. For each bignum, it emits a 16-byte integer.
  984.  
  985.    The term "octa" comes from contexts in which a "word" is two bytes;
  986. hence *octa*-word for 16 bytes.
  987.  
  988. 
  989. File: as.info,  Node: Org,  Next: Psize,  Prev: Octa,  Up: Pseudo Ops
  990.  
  991. `.org NEW-LC , FILL'
  992. ====================
  993.  
  994.    Advance the location counter of the current section to NEW-LC.
  995. nEW-LC is either an absolute expression or an expression with the same
  996. section as the current subsection.  That is, you can't use `.org' to
  997. cross sections: if NEW-LC has the wrong section, the `.org' directive
  998. is ignored.  To be compatible with former assemblers, if the section of
  999. NEW-LC is absolute, `as' issues a warning, then pretends the section of
  1000. NEW-LC is the same as the current subsection.
  1001.  
  1002.    `.org' may only increase the location counter, or leave it
  1003. unchanged; you cannot use `.org' to move the location counter backwards.
  1004.  
  1005.    Because `as' tries to assemble programs in one pass, NEW-LC may not
  1006. be undefined.  If you really detest this restriction we eagerly await a
  1007. chance to share your improved assembler.
  1008.  
  1009.    Beware that the origin is relative to the start of the section, not
  1010. to the start of the subsection.  This is compatible with other people's
  1011. assemblers.
  1012.  
  1013.    When the location counter (of the current subsection) is advanced,
  1014. the intervening bytes are filled with FILL which should be an absolute
  1015. expression.  If the comma and FILL are omitted, FILL defaults to zero.
  1016.  
  1017. 
  1018. File: as.info,  Node: Psize,  Next: Quad,  Prev: Org,  Up: Pseudo Ops
  1019.  
  1020. `.psize LINES , COLUMNS'
  1021. ========================
  1022.  
  1023.    Use this directive to declare the number of lines--and, optionally,
  1024. the number of columns--to use for each page, when generating listings.
  1025.  
  1026.    If you do not use `.psize', listings use a default line-count of 60.
  1027. You may omit the comma and COLUMNS specification; the default width is
  1028. 200 columns.
  1029.  
  1030.    `as' generates formfeeds whenever the specified number of lines is
  1031. exceeded (or whenever you explicitly request one, using `.eject').
  1032.  
  1033.    If you specify LINES as `0', no formfeeds are generated save those
  1034. explicitly specified with `.eject'.
  1035.  
  1036. 
  1037. File: as.info,  Node: Quad,  Next: Sbttl,  Prev: Psize,  Up: Pseudo Ops
  1038.  
  1039. `.quad BIGNUMS'
  1040. ===============
  1041.  
  1042.    `.quad' expects zero or more bignums, separated by commas.  For each
  1043. bignum, it emits an 8-byte integer.  If the bignum won't fit in 8
  1044. bytes, it prints a warning message; and just takes the lowest order 8
  1045. bytes of the bignum.
  1046.  
  1047.    The term "quad" comes from contexts in which a "word" is two bytes;
  1048. hence *quad*-word for 8 bytes.
  1049.  
  1050. 
  1051. File: as.info,  Node: Sbttl,  Next: Scl,  Prev: Quad,  Up: Pseudo Ops
  1052.  
  1053. `.sbttl "SUBHEADING"'
  1054. =====================
  1055.  
  1056.    Use SUBHEADING as the title (third line, immediately after the title
  1057. line) when generating assembly listings.
  1058.  
  1059.    This directive affects subsequent pages, as well as the current page
  1060. if it appears within ten lines of the top of a page.
  1061.  
  1062. 
  1063. File: as.info,  Node: Scl,  Next: Section,  Prev: Sbttl,  Up: Pseudo Ops
  1064.  
  1065. `.scl CLASS'
  1066. ============
  1067.  
  1068.    Set the storage-class value for a symbol.  This directive may only be
  1069. used inside a `.def'/`.endef' pair.  Storage class may flag whether a
  1070. symbol is static or external, or it may record further symbolic
  1071. debugging information.
  1072.  
  1073.    The `.scl' directive is primarily associated with COFF output; when
  1074. configured to generate `b.out' output format, `as' accepts this
  1075. directive but ignores it.
  1076.  
  1077. 
  1078. File: as.info,  Node: Section,  Next: Set,  Prev: Scl,  Up: Pseudo Ops
  1079.  
  1080. `.section NAME, SUBSECTION'
  1081. ===========================
  1082.  
  1083.    Assemble the following code into end of subsection numbered
  1084. SUBSECTION in the COFF named section NAME.  If you omit SUBSECTION,
  1085. `as' uses subsection number zero.  `.section .text' is equivalent to
  1086. the `.text' directive; `.section .data' is equivalent to the `.data'
  1087. directive.  This directive is only supported for targets that actually
  1088. support arbitrarily named sections; on `a.out' targets, for example, it
  1089. is not accepted, even with a standard `a.out' section name as its
  1090. parameter.
  1091.  
  1092. 
  1093. File: as.info,  Node: Set,  Next: Short,  Prev: Section,  Up: Pseudo Ops
  1094.  
  1095. `.set SYMBOL, EXPRESSION'
  1096. =========================
  1097.  
  1098.    Set the value of SYMBOL to EXPRESSION.  This changes SYMBOL's value
  1099. and type to conform to EXPRESSION.  If SYMBOL was flagged as external,
  1100. it remains flagged. (*Note Symbol Attributes::.)
  1101.  
  1102.    You may `.set' a symbol many times in the same assembly.
  1103.  
  1104.    If you `.set' a global symbol, the value stored in the object file
  1105. is the last value stored into it.
  1106.  
  1107.    The syntax for `set' on the HPPA is `SYMBOL .set EXPRESSION'.
  1108.  
  1109. 
  1110. File: as.info,  Node: Short,  Next: Single,  Prev: Set,  Up: Pseudo Ops
  1111.  
  1112. `.short EXPRESSIONS'
  1113. ====================
  1114.  
  1115.    `.short' is normally the same as `.word'.  *Note `.word': Word.
  1116.  
  1117.    In some configurations, however, `.short' and `.word' generate
  1118. numbers of different lengths; *note Machine Dependencies::..
  1119.  
  1120. 
  1121. File: as.info,  Node: Single,  Next: Size,  Prev: Short,  Up: Pseudo Ops
  1122.  
  1123. `.single FLONUMS'
  1124. =================
  1125.  
  1126.    This directive assembles zero or more flonums, separated by commas.
  1127. It has the same effect as `.float'.  The exact kind of floating point
  1128. numbers emitted depends on how `as' is configured.  *Note Machine
  1129. Dependencies::.
  1130.  
  1131. 
  1132. File: as.info,  Node: Size,  Next: Space,  Prev: Single,  Up: Pseudo Ops
  1133.  
  1134. `.size'
  1135. =======
  1136.  
  1137.    This directive is generated by compilers to include auxiliary
  1138. debugging information in the symbol table.  It is only permitted inside
  1139. `.def'/`.endef' pairs.
  1140.  
  1141.    `.size' is only meaningful when generating COFF format output; when
  1142. `as' is generating `b.out', it accepts this directive but ignores it.
  1143.  
  1144. 
  1145. File: as.info,  Node: Space,  Next: Stab,  Prev: Size,  Up: Pseudo Ops
  1146.  
  1147. `.space SIZE , FILL'
  1148. ====================
  1149.  
  1150.    This directive emits SIZE bytes, each of value FILL.  Both SIZE and
  1151. FILL are absolute expressions.  If the comma and FILL are omitted, FILL
  1152. is assumed to be zero.
  1153.  
  1154.      *Warning:* `.space' has a completely different meaning for HPPA
  1155.      targets; use `.block' as a substitute.  See `HP9000 Series 800
  1156.      Assembly Language Reference Manual' (HP 92432-90001) for the
  1157.      meaning of the `.space' directive.  *Note HPPA Assembler
  1158.      Directives: HPPA Directives, for a summary.
  1159.  
  1160.    On the AMD 29K, this directive is ignored; it is accepted for
  1161. compatibility with other AMD 29K assemblers.
  1162.  
  1163.      *Warning:* In most versions of the GNU assembler, the directive
  1164.      `.space' has the effect of `.block'  *Note Machine Dependencies::.
  1165.  
  1166. 
  1167. File: as.info,  Node: Stab,  Next: String,  Prev: Space,  Up: Pseudo Ops
  1168.  
  1169. `.stabd, .stabn, .stabs'
  1170. ========================
  1171.  
  1172.    There are three directives that begin `.stab'.  All emit symbols
  1173. (*note Symbols::.), for use by symbolic debuggers.  The symbols are not
  1174. entered in the `as' hash table: they cannot be referenced elsewhere in
  1175. the source file.  Up to five fields are required:
  1176.  
  1177. STRING
  1178.      This is the symbol's name.  It may contain any character except
  1179.      `\000', so is more general than ordinary symbol names.  Some
  1180.      debuggers used to code arbitrarily complex structures into symbol
  1181.      names using this field.
  1182.  
  1183. TYPE
  1184.      An absolute expression.  The symbol's type is set to the low 8
  1185.      bits of this expression.  Any bit pattern is permitted, but `ld'
  1186.      and debuggers choke on silly bit patterns.
  1187.  
  1188. OTHER
  1189.      An absolute expression.  The symbol's "other" attribute is set to
  1190.      the low 8 bits of this expression.
  1191.  
  1192. DESC
  1193.      An absolute expression.  The symbol's descriptor is set to the low
  1194.      16 bits of this expression.
  1195.  
  1196. VALUE
  1197.      An absolute expression which becomes the symbol's value.
  1198.  
  1199.    If a warning is detected while reading a `.stabd', `.stabn', or
  1200. `.stabs' statement, the symbol has probably already been created; you
  1201. get a half-formed symbol in your object file.  This is compatible with
  1202. earlier assemblers!
  1203.  
  1204. `.stabd TYPE , OTHER , DESC'
  1205.      The "name" of the symbol generated is not even an empty string.
  1206.      It is a null pointer, for compatibility.  Older assemblers used a
  1207.      null pointer so they didn't waste space in object files with empty
  1208.      strings.
  1209.  
  1210.      The symbol's value is set to the location counter, relocatably.
  1211.      When your program is linked, the value of this symbol is the
  1212.      address of the location counter when the `.stabd' was assembled.
  1213.  
  1214. `.stabn TYPE , OTHER , DESC , VALUE'
  1215.      The name of the symbol is set to the empty string `""'.
  1216.  
  1217. `.stabs STRING ,  TYPE , OTHER , DESC , VALUE'
  1218.      All five fields are specified.
  1219.  
  1220. 
  1221. File: as.info,  Node: String,  Next: Tag,  Prev: Stab,  Up: Pseudo Ops
  1222.  
  1223. `.string' "STR"
  1224. ===============
  1225.  
  1226.    Copy the characters in STR to the object file.  You may specify more
  1227. than one string to copy, separated by commas.  Unless otherwise
  1228. specified for a particular machine, the assembler marks the end of each
  1229. string with a 0 byte.  You can use any of the escape sequences
  1230. described in *Note Strings: Strings.
  1231.  
  1232. 
  1233. File: as.info,  Node: Tag,  Next: Text,  Prev: String,  Up: Pseudo Ops
  1234.  
  1235. `.tag STRUCTNAME'
  1236. =================
  1237.  
  1238.    This directive is generated by compilers to include auxiliary
  1239. debugging information in the symbol table.  It is only permitted inside
  1240. `.def'/`.endef' pairs.  Tags are used to link structure definitions in
  1241. the symbol table with instances of those structures.
  1242.  
  1243.    `.tag' is only used when generating COFF format output; when `as' is
  1244. generating `b.out', it accepts this directive but ignores it.
  1245.  
  1246. 
  1247. File: as.info,  Node: Text,  Next: Title,  Prev: Tag,  Up: Pseudo Ops
  1248.  
  1249. `.text SUBSECTION'
  1250. ==================
  1251.  
  1252.    Tells `as' to assemble the following statements onto the end of the
  1253. text subsection numbered SUBSECTION, which is an absolute expression.
  1254. If SUBSECTION is omitted, subsection number zero is used.
  1255.  
  1256. 
  1257. File: as.info,  Node: Title,  Next: Type,  Prev: Text,  Up: Pseudo Ops
  1258.  
  1259. `.title "HEADING"'
  1260. ==================
  1261.  
  1262.    Use HEADING as the title (second line, immediately after the source
  1263. file name and pagenumber) when generating assembly listings.
  1264.  
  1265.    This directive affects subsequent pages, as well as the current page
  1266. if it appears within ten lines of the top of a page.
  1267.  
  1268. 
  1269. File: as.info,  Node: Type,  Next: Val,  Prev: Title,  Up: Pseudo Ops
  1270.  
  1271. `.type INT'
  1272. ===========
  1273.  
  1274.    This directive, permitted only within `.def'/`.endef' pairs, records
  1275. the integer INT as the type attribute of a symbol table entry.
  1276.  
  1277.    `.type' is associated only with COFF format output; when `as' is
  1278. configured for `b.out' output, it accepts this directive but ignores it.
  1279.  
  1280. 
  1281. File: as.info,  Node: Val,  Next: Word,  Prev: Type,  Up: Pseudo Ops
  1282.  
  1283. `.val ADDR'
  1284. ===========
  1285.  
  1286.    This directive, permitted only within `.def'/`.endef' pairs, records
  1287. the address ADDR as the value attribute of a symbol table entry.
  1288.  
  1289.    `.val' is used only for COFF output; when `as' is configured for
  1290. `b.out', it accepts this directive but ignores it.
  1291.  
  1292. 
  1293. File: as.info,  Node: Word,  Next: Deprecated,  Prev: Val,  Up: Pseudo Ops
  1294.  
  1295. `.word EXPRESSIONS'
  1296. ===================
  1297.  
  1298.    This directive expects zero or more EXPRESSIONS, of any section,
  1299. separated by commas.
  1300.  
  1301.    The size of the number emitted, and its byte order, depend on what
  1302. target computer the assembly is for.
  1303.  
  1304.      *Warning: Special Treatment to support Compilers*
  1305.  
  1306.    Machines with a 32-bit address space, but that do less than 32-bit
  1307. addressing, require the following special treatment.  If the machine of
  1308. interest to you does 32-bit addressing (or doesn't require it; *note
  1309. Machine Dependencies::.), you can ignore this issue.
  1310.  
  1311.    In order to assemble compiler output into something that works, `as'
  1312. occasionlly does strange things to `.word' directives.  Directives of
  1313. the form `.word sym1-sym2' are often emitted by compilers as part of
  1314. jump tables.  Therefore, when `as' assembles a directive of the form
  1315. `.word sym1-sym2', and the difference between `sym1' and `sym2' does
  1316. not fit in 16 bits, `as' creates a "secondary jump table", immediately
  1317. before the next label.  This secondary jump table is preceded by a
  1318. short-jump to the first byte after the secondary table.  This
  1319. short-jump prevents the flow of control from accidentally falling into
  1320. the new table.  Inside the table is a long-jump to `sym2'.  The
  1321. original `.word' contains `sym1' minus the address of the long-jump to
  1322. `sym2'.
  1323.  
  1324.    If there were several occurrences of `.word sym1-sym2' before the
  1325. secondary jump table, all of them are adjusted.  If there was a `.word
  1326. sym3-sym4', that also did not fit in sixteen bits, a long-jump to
  1327. `sym4' is included in the secondary jump table, and the `.word'
  1328. directives are adjusted to contain `sym3' minus the address of the
  1329. long-jump to `sym4'; and so on, for as many entries in the original
  1330. jump table as necessary.
  1331.  
  1332. 
  1333. File: as.info,  Node: Deprecated,  Prev: Word,  Up: Pseudo Ops
  1334.  
  1335. Deprecated Directives
  1336. =====================
  1337.  
  1338.    One day these directives won't work.  They are included for
  1339. compatibility with older assemblers.
  1340. .abort
  1341. .app-file
  1342. .line
  1343. 
  1344. File: as.info,  Node: Machine Dependencies,  Next: Acknowledgements,  Prev: Pseudo Ops,  Up: Top
  1345.  
  1346. Machine Dependent Features
  1347. **************************
  1348.  
  1349.    The machine instruction sets are (almost by definition) different on
  1350. each machine where `as' runs.  Floating point representations vary as
  1351. well, and `as' often supports a few additional directives or
  1352. command-line options for compatibility with other assemblers on a
  1353. particular platform.  Finally, some versions of `as' support special
  1354. pseudo-instructions for branch optimization.
  1355.  
  1356.    This chapter discusses most of these differences, though it does not
  1357. include details on any machine's instruction set.  For details on that
  1358. subject, see the hardware manufacturer's manual.
  1359.  
  1360. * Menu:
  1361.  
  1362.  
  1363. * Vax-Dependent::               VAX Dependent Features
  1364.  
  1365. * AMD29K-Dependent::            AMD 29K Dependent Features
  1366.  
  1367. * H8/300-Dependent::            Hitachi H8/300 Dependent Features
  1368.  
  1369. * H8/500-Dependent::            Hitachi H8/500 Dependent Features
  1370.  
  1371. * HPPA-Dependent::              HPPA Dependent Features
  1372.  
  1373. * SH-Dependent::                Hitachi SH Dependent Features
  1374.  
  1375. * i960-Dependent::              Intel 80960 Dependent Features
  1376.  
  1377. * M68K-Dependent::              M680x0 Dependent Features
  1378.  
  1379. * Sparc-Dependent::             SPARC Dependent Features
  1380.  
  1381. * Z8000-Dependent::             Z8000 Dependent Features
  1382.  
  1383. * MIPS-Dependent::              MIPS Dependent Features
  1384.  
  1385. * i386-Dependent::              80386 Dependent Features
  1386.  
  1387. 
  1388. File: as.info,  Node: Vax-Dependent,  Next: AMD29K-Dependent,  Up: Machine Dependencies
  1389.  
  1390. VAX Dependent Features
  1391. ======================
  1392.  
  1393. * Menu:
  1394.  
  1395. * Vax-Opts::                    VAX Command-Line Options
  1396. * VAX-float::                   VAX Floating Point
  1397. * VAX-directives::              Vax Machine Directives
  1398. * VAX-opcodes::                 VAX Opcodes
  1399. * VAX-branch::                  VAX Branch Improvement
  1400. * VAX-operands::                VAX Operands
  1401. * VAX-no::                      Not Supported on VAX
  1402.  
  1403. 
  1404. File: as.info,  Node: Vax-Opts,  Next: VAX-float,  Up: Vax-Dependent
  1405.  
  1406. VAX Command-Line Options
  1407. ------------------------
  1408.  
  1409.    The Vax version of `as' accepts any of the following options, gives
  1410. a warning message that the option was ignored and proceeds.  These
  1411. options are for compatibility with scripts designed for other people's
  1412. assemblers.
  1413.  
  1414. ``-D' (Debug)'
  1415. ``-S' (Symbol Table)'
  1416. ``-T' (Token Trace)'
  1417.      These are obsolete options used to debug old assemblers.
  1418.  
  1419. ``-d' (Displacement size for JUMPs)'
  1420.      This option expects a number following the `-d'.  Like options
  1421.      that expect filenames, the number may immediately follow the `-d'
  1422.      (old standard) or constitute the whole of the command line
  1423.      argument that follows `-d' (GNU standard).
  1424.  
  1425. ``-V' (Virtualize Interpass Temporary File)'
  1426.      Some other assemblers use a temporary file.  This option commanded
  1427.      them to keep the information in active memory rather than in a
  1428.      disk file.  `as' always does this, so this option is redundant.
  1429.  
  1430. ``-J' (JUMPify Longer Branches)'
  1431.      Many 32-bit computers permit a variety of branch instructions to
  1432.      do the same job.  Some of these instructions are short (and fast)
  1433.      but have a limited range; others are long (and slow) but can
  1434.      branch anywhere in virtual memory.  Often there are 3 flavors of
  1435.      branch: short, medium and long.  Some other assemblers would emit
  1436.      short and medium branches, unless told by this option to emit
  1437.      short and long branches.
  1438.  
  1439. ``-t' (Temporary File Directory)'
  1440.      Some other assemblers may use a temporary file, and this option
  1441.      takes a filename being the directory to site the temporary file.
  1442.      Since `as' does not use a temporary disk file, this option makes
  1443.      no difference.  `-t' needs exactly one filename.
  1444.  
  1445.    The Vax version of the assembler accepts two options when compiled
  1446. for VMS.  They are `-h', and `-+'.  The `-h' option prevents `as' from
  1447. modifying the symbol-table entries for symbols that contain lowercase
  1448. characters (I think).  The `-+' option causes `as' to print warning
  1449. messages if the FILENAME part of the object file, or any symbol name is
  1450. larger than 31 characters.  The `-+' option also inserts some code
  1451. following the `_main' symbol so that the object file is compatible with
  1452. Vax-11 "C".
  1453.  
  1454. 
  1455. File: as.info,  Node: VAX-float,  Next: VAX-directives,  Prev: Vax-Opts,  Up: Vax-Dependent
  1456.  
  1457. VAX Floating Point
  1458. ------------------
  1459.  
  1460.    Conversion of flonums to floating point is correct, and compatible
  1461. with previous assemblers.  Rounding is towards zero if the remainder is
  1462. exactly half the least significant bit.
  1463.  
  1464.    `D', `F', `G' and `H' floating point formats are understood.
  1465.  
  1466.    Immediate floating literals (*e.g.* `S`$6.9') are rendered
  1467. correctly.  Again, rounding is towards zero in the boundary case.
  1468.  
  1469.    The `.float' directive produces `f' format numbers.  The `.double'
  1470. directive produces `d' format numbers.
  1471.  
  1472.